package org.marketlive.system.config;

import java.util.ResourceBundle;


/*
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
*/

/**
 * Manages configuration information.  
 * Aggregates configuration data from many different sources, including
 * database tables, property files, and XML files.</p>
 *
 * Configuration values are organized into a tree structure.
 * The base of the tree is the Root.
 * Each branch is represented by a path from the Root.
 * The terminus of each branch is a leaf and associated with each leaf is a value.</p>
 *
 * The underlying datastore may contain information for multiple clients,
 * environments, and so on.  The IConfigurationContext is used to select a particular
 * set of data.
 */
public interface IConfigurationManager {

    /**
     * Returns the root of the configuration tree.
     *
     * @return the <code>IConfigurationBranch</code> that is the root of the configuration tree
     */
    IConfigurationBranch getRoot();

    /**
     * Returns the branch node for the given path.
     *
     * @param path the path containing the desired node
     * 
     * @return the <code>IConfigurationBranch</code> the node for given path
     */
    IConfigurationBranch getBranch(String path);

    /**
     * Returns the active configuration context.
     * 
     * @return the <code>IConfigurationContext</code> - the active configuration context
     */
    IConfigurationContext getContext();

    /**
     * Tests if SSL security is expected to be functioning.
     * 
     * @return true if SSL security is expected to be functioning; false otherwise
     */
    boolean isGoSecure();    

    /**
     * Returns the value associated with the given configuration leaf.
     *
     * @param name the leaf name, including the full path
     * 
     * @return the string value of the given configuration leaf
     */
    String getAsString(String name);

    /**
     * Returns the int value associated with given configuration leaf.
     * 
     * @param name the leaf name, including the full path
     * 
     * @return the int value of the given configuration leaf
     */
    int getAsInt(String name);

    /**
     * Returns the boolean value associated with the given configuration leaf.
     *
     * @param name the leaf name, including the full path
     * 
     * @return the boolean value of the given configuration leaf
     */
    boolean getAsBoolean(String name);

    /**
     * Returns the boolean value associated with the given configuration leaf, or the default value
     * if the leaf does not exist. 
     *
     * @param name of the variable, including the full path
     * @param defaultValue boolean return associated with configuration
     * @return value associated with leaf as boolean if found; <code>defaultValue</code> otherwise
     */
    boolean getAsBoolean(String name, boolean defaultValue);

    /**
     * Registers a given <code>ResourceBundle</code> with the given path.
     * 
     * @param path to associate with bundle
     * @param bundle to associate with path
     */
    void registerBundle(String path, ResourceBundle bundle);

    /**
     * Returns a complete output of the current configuration.
     *
     * @return the configuration
     */
    String printConfiguration();

    /**
     * Initializes the tree with the given root.
     *  
     * @param configurationRoot to use as the root of this tree
     */
    void init(String configurationRoot);

    /**
     * Returns true if the branch exists; false if it does not.
     * 
     * @param name the variable, including the full path
     * @return true if the branch exists; false otherwise
     */
    boolean isBranchDefined(String name);

}
